package org.dreamwork.jasmine2.engine;

import java.io.IOException;

/**
 * 状态管理器
 *
 * <p>状态管理器定义了一组接口用于处理页面及控件的状态。
 * <p>原始 http 请求为无状态请求，后续页面，特别是后续的同一页面对象需要额外数据来分析当前页面所处的状态。状态管理器提供了一个同一的接口
 * 来保存、读取和管理状态。
 * <p>当一个 jasmine 页面被渲染时，页面及页面上的每一个控件都将拥有一个确定的状态，该状态在页面被回传(postback)时同时提交到服务器端，
 * 以供事件派发流程使用。
 * <p>当 jasmine 页面或 jasmine 控件准备开始渲染时，状态管理器锁定控件状态，不允许应用程序修改控件状态来保证控件渲染的结果和保存的状态
 * 是一致的。当试图在控件预渲染生命周期内进行修改控件状态，IStateManager 将跑出 java.lang.IllegalState 异常。<br>
 * 在控件渲染完成后对控件进行的任何修改将被忽略。
 *
 * Created by IntelliJ IDEA.
 * User: seth
 * Date: 2009-2-4
 * Time: 10:23:39
 */
public interface IStateManager {
    /**
     * 是否正在跟踪视图状态
     * @return true - 正在跟踪，否则返回 false
     */
    boolean isTrackingViewState ();

    /**
     * 装载视图状态
     * <p>从一个序列化对象中恢复视图状态，该对象是由 IStateManager.save 上次保存的
     *
     * @param loadedState 序列化对象
     * @throws IOException IO异常
     */
    void loadViewState (Object loadedState) throws IOException;

    /**
     * 保存视图状态
     * @return 序列化对象
     * @throws IOException IO异常
     */
    Object saveViewState () throws IOException;

    /**
     * 开始跟踪试图状态。
     * <p>控件状态处于锁定模式，任何修改都导致 java.lang.IllegalState 异常。<br>
     * 通过 IStateManger.isTrackingViewState 方法来确定视图对象的模式。
     * <p>调用 IStateManager.stopTrackViewState 可以中断对试图状态的跟踪，以恢复视图状态的可写模式。
     */
    void trackViewState();

    /**
     * 停止跟踪试图状态.
     * <p>该方法由 jasmine 引擎调用，<strong>应用程序应尽量避免调用该方法，以避免破坏视图状态的一致性</strong>
     */
    void stopTrackViewState ();

    /**
     * 在视图状态管理器中获取一个属性
     * @param name 属性名称
     * @return 属性值
     */
    Object get (Object name);

    /**
     * 向管理器中保存一个属性
     * @param name 属性名称
     * @param value 属性值
     * @return 属性值
     */
    Object put (Object name, Object value);

    /**
     * 从管理器中删除一个属性
     * @param key 属性名称
     * @return 属性值
     */
    Object remove (Object key);
}